feat: expose headless wallet list imperatively on the AppKit client#5695
Merged
Conversation
The headless wallet flow (list/search/paginate WalletGuide wallets, fetch the WC URI, and programmatic connect for injected/API/mobile wallets) lived only inside the `useAppKitWallets` React hook, so non-React hosts couldn't drive it. Lift the imperative core into a new `HeadlessWalletUtil` (@reown/appkit-controllers) and expose it on the AppKit client: - AppKit instance methods: fetchWallets / getWalletList / subscribeWalletList / getWalletConnectUri / connectWallet. - HeadlessWalletUtil holds the shared logic (reads/writes the global controllers, no AppKit instance — same pattern as ConnectionControllerUtil), so the client methods and the React hook share one code path. Follow-up: refactor useAppKitWallets to delegate to HeadlessWalletUtil (dedup); kept out of this change to keep the diff additive. + HeadlessWalletUtil unit tests, changeset. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The hook redefined ConnectOptions/FetchWalletsOptions that now live in HeadlessWalletUtil; re-export them from there (one declaration) to resolve the ambiguous re-export in @reown/appkit's react build. Drop the now-unused BadgeType import + tidy comment/cast lint. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: f633c68 The changes in this PR will be included in the next version bump. This PR includes changesets to release 26 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
enesozturk
commented
Jun 26, 2026
| @@ -0,0 +1,8 @@ | |||
| --- | |||
| '@reown/appkit-controllers': minor | |||
Contributor
Author
There was a problem hiding this comment.
Add all packages here, not just the affected ones
Contributor
Author
There was a problem hiding this comment.
Done in d5d9655 — the changeset now lists all packages (repo lockstep convention).
|
The latest updates on your projects. Learn more about Vercel for GitHub.
9 Skipped Deployments
|
Contributor
Visual Regression Test Results ✅ PassedChromatic Build: https://www.chromatic.com/build?appId=6493191bf4b10fed8ca7353f&number=942 👉 Please review the visual changes in Chromatic and accept or reject them. |
0xmkh
approved these changes
Jun 26, 2026
Contributor
📦 Bundle Size Check✅ All bundles are within size limits 📊 View detailed bundle sizes> @reown/appkit-monorepo@1.7.1 size /home/runner/work/appkit/appkit > size-limit |
…less
- changeset: list all packages (repo lockstep convention), per review.
- examples/html-headless: a vanilla-JS wallet modal driven entirely by the new
imperative client API — first page via appKit.fetchWallets({ page }), infinite
loading on scroll (appends), live re-render via subscribeWalletList, and
connectWallet on click. No React, no AppKit modal. Builds clean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
Author
|
Added
No React, no AppKit modal. Builds clean ( |
Contributor
Apply prettier to the touched files and convert the new client-method header to a block comment (multiline-comment-style / capitalized-comments lint). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`TronWalletConnectConnector.ts` (from #5694, current main) has 4 consecutive line comments that violate `multiline-comment-style`, failing `code_style (lint)` for every branch off main. Convert to a block comment to unblock CI. Unrelated to this PR's changes, but main's lint is red without it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Exposes the headless wallet list imperatively on the AppKit client, so a non-React host can list / search / connect wallets without the
useAppKitWalletsReact hook.Why
The headless wallet flow — list/search/paginate WalletGuide wallets, fetch the WalletConnect URI, and programmatically connect injected / API / mobile-deeplink wallets — lived only inside the
useAppKitWalletsReact hook (packages/controllers/exports/react.ts), reaching into the controllers and re-implementing the connect logic. A non-React consumer (e.g.@walletconnect/pay-appkit, which drives a fully custom checkout) has no way to reach it.This lifts the imperative core onto the client so React and non-React hosts share one tested code path.
Changes
HeadlessWalletUtil(new,@reown/appkit-controllers) — the framework-neutral core:fetchWallets/getWalletList/subscribeWalletList/getWalletConnectUri/connect/resetWcUri/resetConnectingWallet. Reads/writes the global controllers directly (no AppKit instance), exactly likeConnectionControllerUtil. The connect logic (injected → API-wallet fallback → mobile deeplink → WalletConnect) is lifted verbatim from the hook.appkit-base-client.ts):appKit.fetchWallets(options?),appKit.getWalletList(),appKit.subscribeWalletList(cb),appKit.getWalletConnectUri(options?),appKit.connectWallet(wallet, namespace?, options?)— each delegating toHeadlessWalletUtil.ConnectOptions/FetchWalletsOptionsnow have a single home inHeadlessWalletUtil; the hook re-exports them (resolves the previous duplicate-definition).getWalletInfo/getApprovedCaipNetworkIds/getAccount/subscribeAccount/subscribeConnections(which carrywcUri/wcError) already exist on the client, so no new surface was needed for connected-wallet info or the WC URI state.Follow-up (intentionally out of scope)
Refactor
useAppKitWalletsto delegate itsconnect/fetchWallets/getWcUribodies toHeadlessWalletUtil(dedup the logic). Kept out to keep this diff additive; the hook already shares the option types and is unaffected behaviorally.Validation
@reown/appkit-controllersbuild ✅ ·@reown/appkitbuild ✅HeadlessWalletUtilunit tests — 14/14 (fetch/search/list, the full connect matrix incl. mobile deeplink, WC URI, resets)useAppKitWalletshook tests — 45/45 (unchanged)Context
Enables
@walletconnect/pay-appkit(the WalletConnect Pay headless SDK adapter) to drive headless wallet listing/connect from a framework-neutral entry — and any pure-JS host to do the same — instead of being limited to the React hook.